Python 3 Navigation API

This topic explains how to set up and use Navigation in Python 3. It is intended to help users understand the basic concepts before writing scripts for a layout.

Navigation allows you to define walkable areas, obstacles, and moving agents. The generated navigation mesh is then used by agents to move through the scene.

Overview

A layout contains a single Navigation behavior. A Navigation behavior can contain one or more navigation units.

A navigation unit is the container for:

Pathways
Obstacles
Agents
The generated navigation mesh

All agents in the same navigation unit share the same navigation mesh.

Navigation components

Navigation behavior

The Navigation behavior is the root object for navigation in the layout. It provides access to the navigation unit or units used in the current world.

import vcCore as vc

world = vc.getWorld()
nav_beh = world.findBehavior("Navigation")

Navigation unit

A navigation unit is the main map object for a navigation setup. It is the object you create first when you want agents to move in a layout.

nav = nav_beh.createNavUnit("MyNavUnit")

The actual wrapper signature is:

```
nav_beh.createNavUnit(id)
```

This creates or retrieves a vcNavUnit.

Pathways

A pathway is a navigable area that agents can travel through. It defines the walkable space used to build the mesh.

for child in world.Components:
  if "Pathway in child.Name:
    bound = child.BoundingBox.HalfDiagonal
    nav.addPathway(child.WorldPositionMatrix, bound.X, bound.Y)

Method signature:

nav.addPathway(center, bx, by, fromPoint=None, toPoint=None, areaId=None)

Parameters:

center : vcMatrix - center matrix of the pathway in world space.
bx : float - half-width of the pathway in the local X direction.
by : float - half-width of the pathway in the local Y direction.
fromPoint : vcVector (optional) - start point for a directional pathway.
toPoint : vcVector (optional) - end point for a directional pathway.
areaId : int (optional) - restricted pathway area identifier.

Obstacles

An obstacle blocks or influences movement. It is typically used for walls, machines, fixtures or other non-traversable objects.

for child in world.Components:
  if "Obstacle" in child.Name:
    bound = child.BoundingBox
    bc = bound.Center
    center_wpm = child.WorldPositionMatrix
    center_wpm.translateRel(bc.X, bc.Y, bc.Z)
    
    bd = bound.HalfDiagonal
    nav.addObstacle(center_wpm, bd)

Method signature:

```
nav.addObstacle(center, boundDiagonal)
```

Parameters:

center : vcMatrix - obstacle center position in world space.
boundDiagonal : vcVector - dimensions of the obstacle as a bounding diagonal vector.

Agents

An agent is a moving object that uses the navigation mesh to reach a target position.

for child in world.Components:
  if "Agent" in child.Name:
    agent = nav.createAgent(child)
    agent.Radius = 250.0
    agent.Height = 100.0
    agent.MaxVelocity = 500.0
    agent.MaxAcceleration = 500.0
    agent.MaxAngularVelocity = 45.0
    agent.MaxAngularAcceleration = 10.0
    agent.CollisionQueryRange = 3000.0
    agent.SeparationWeight = 0.5
    agent.TurnInPlaceThreshold = 60.0
    agent.CornerAssistWeight = 0.0
    agent.ProximityAssistWeight = 0.0

Method signature:

```
nav.createAgent(component)
```

Parameters:

component : vcComponent - the component that should own the agent.

Returns:

vcNavAgent - the created or existing agent for that component.

Navigation geometry and movement tuning

Navigation depends on two different things:

Navigation geometry

Navigation geometry defines where an agent can move. This includes pathways and any obstacles or blocked regions that affect the generated navigation mesh.

Examples:

Pathways
Walls
Blocked areas
Obstacles
Non-traversable regions

These elements determine the walkable region and therefore define where the agent can navigate.

Movement tuning

Movement tuning controls how an agent moves within the navigation mesh. These settings affect avoidance, turning, and local path behavior, but they do not define the walkable area itself.

Examples:

Separation between nearby agents
Turn-in-place threshold
Corner slowdown behavior
proximity slowdown behavior

These values influence how an agent reacts to its surroundings, but they do not change the mesh geometry.

Typical workflow

The normal workflow is:

Get the Navigation behavior
Create a navigation unit
Add pathways
Add obstacles
Create agents
Configure agent settings
Build the navigation mesh
Steer agents to targets

Build the navigation mesh

After pathways, obstacles, and agents are added, the mesh must be built.

nav.buildMap(250.0, 800.0, 30.0, True)

Method signature:

nav.buildMap(maxAgentRadius, maxAgentHeight, walkableHeight, keepMeshData)

Parameters:

maxAgentRadius : float - maximum radius of the navigation agents in millimeters.
maxAgentHeight : float - maximum height of the navigation agents in millimeters.
walkableHeight : float - maximum traversable ledge height in millimeters.
keepMeshData : bool - True keeps mesh data for visualization or debugging; False releases it after the mesh is created.

This call builds the navigation mesh based on the defined pathways, obstacles, and current agent parameters.

Important:

The values are in millimeters.
walkableHeight : defines the maximum height that can be traversed.
keepMeshData : affects memory usage and debugging access.

Steer an agent

Once the map exists, agents can be steered to target positions.

if nav.Agents:
  agent = nav.Agents[0]
      
  destination_matrix = vc.vcMatrix.new()
  destination_matrix.Px = 1000.0
  destination_matrix.Py = 1000.0
      
  agent.autoSteerTo(destination_matrix.P, 45.0)

agent.autoSteerTo(position, heading=None)

Parameters:

position : vcVector - target position to steer the agent to.
heading: float or None (optional) - final heading in degrees.

Returns:

bool - indicates whether the steering operation was started successfully.

This method calculates a path and follows it while avoiding obstacles.

Manual steering is also available:

agent.manualSteerTo(destination_matrix.P, 135.0)

agent.manualSteerTo(position, heading=None)

Parameters:

position : vcVector - target position to steer the agent to.
heading: float or None (optional) - final heading in degrees.

Returns:

bool - indicates whether the steering operation was started successfully.

This method steers the agent directly toward the target position without full pathfinding.

Complete example

import vcCore as vc

comp = vc.getComponent()
world = vc.getWorld()
nav_beh = world.findBehavior("Navigation")
    
nav = nav_beh.createNavUnit(comp.Name)

for child in world.Components:
  if "Pathway" in child.Name:
    bound = child.BoundingBox.HalfDiagonal
    nav.addPathway(child.WorldPositionMatrix, bound.X, bound.Y)
  
  elif "Obstacle" in child.Name:
    bound = child.BoundingBox
    bc = bound.Center
    center_wpm = child.WorldPositionMatrix
    center_wpm = translateRel(bc.X, bc.Y, bc.Z)
    bd = bound.HalfDiagonal
    nav.addObstacle(center_wpm, bd)
  
  elif "Pathway" in child.Name:
    agent = nav.createAgent(child)
    agent.Radius = 250.0
    agent.Height = 100.0
    agent.MaxVelocity = 500.0
    agent.MaxAcceleration = 500.0
    agent.MaxAngularVelocity = 45.0
    agent.MaxAngularAccelaration = 10.0
    agent.CollisionQueryRange = 3000.0
    agent.SeparationWeight = 0.5
    agent.TurnInPlaceThreshold = 60.0
    agent.CornerAssistWeight = 0.0
    agent.ProximityAssistWeight = 0.0
      
nav = buildMap(250.0, 800.0, 30.0, True)

if nav.Agents:
  agent = nav.Agents[0]
  destination = vc.vcMatrix.new()
  destination.Px = 1000.0
  destination.Py = 1000.0
    
  agent.autoSteerTo(destination.P, 45.0)

Best practices

Use a clear and consistent component selection rule; component names are only one option and may not be the most robust choice in all layouts.
Start with a simple scene and check the generated map before adding complexity.
Keep pathways and obstacles aligned with the layout scale.
Use realistic dimensions for agent radius and height.
Keep CornerAssistWeight and ProximityAssistWeight at 0.0 for the current implementation unless a specific tuning case requires a different value.
Validate the build result before relying on fine-tuned steering behavior.

Troubleshooting

The agent does not move

Check:

Whether the navigation mesh was built.
Whether the correct navigation unit was selected.
Whether the agent was created successfully.
Whether the target is inside a reachable area.

The agent collides with obstacles

Check:

Whether the obstacle was added with the correct bounding box.
Whether the obstacle dimensions match the actual geometry.
Whether the agent radius and collision range are realistic.

The path is not as expected

Check:

Pathway placement.
Obstacle boundaries.
Mesh generation values.
Agent movement tuning.

Related information

For application-side workflow guidance, refer to the Using Resources section in Process Modeling.

This topic is intended to provide a clear introduction before users start implementing navigation logic in scripts.